---
title: 安装和基本使用
---

Univer 采用了插件化的设计理念，旨在为开发者提供一个灵活、可扩展的电子文档应用框架。通过插件化设计，Univer 可以轻松地集成各种功能模块，从而满足不同用户的需求。但插件化的设计会增加应用的复杂性，尤其是对于首次接触 Univer 的开发者来说。

为此，Univer 提供了**插件模式**和**预设模式**两种方式帮助你快速集成和使用 Univer。所谓**预设**实际上就是一组预先配置好的插件组合，因此在无需进行复杂扩展的情况下，两者所提供的能力是相同的。

<Callout type="warning" title="注意事项">
  - **依赖版本需一致**：无论是使用预设模式还是插件模式的方式，你都必须保证所有依赖的版本号一致。
  - **谨慎混用插件和预设**：如果一个插件已经被包含在某个预设中，那么在使用预设时就不需要再单独引入该插件了。否则可能会导致插件冲突或功能异常。
</Callout>

预设模式与插件模式的区别：

| 插件模式 | 预设模式 |
| --- | --- |
| 需要手动引入对应的 facade 包 | 无需手动引入任何 facade 包 |
| 需要注意同类型功能插件注册顺序 | 同功能被包含在预设中无需关注注册顺序 |
| 支持按需懒加载 | 仅支持预设级别的懒加载，预设内的插件包只能同步加载 |

## 通过预设模式创建

在这里我们将简单介绍下如何通过不到二十行的代码来快速搭建一个 Univer Sheets 应用。

### 使用包管理器

如果你的项目中已经引入了现代前端开发工具，那么引入 Univer 将会非常简单。我们推荐使用 [Vite](https://vitejs.dev/)、[esbuild](https://esbuild.github.io/) 或 [Webpack 5](https://webpack.js.org/) 等对 ES Module 支持较好的构建工具来构建 Univer 应用。如果你使用了其它构建工具（例如 Webpack 4），可能会需要一些额外的配置。

#### 安装

选择你所使用的包管理器以安装 `@univerjs/presets`：

```package-install
npm install @univerjs/presets @univerjs/preset-sheets-core
```

#### 使用

<Callout type="warning">
  如果你的构建工具不支持 package.json 的 `exports` 字段（常见于 Webpack 4），你需要手动将映射的路径修改为实际的路径。
</Callout>

通过以下代码，你就可以快速创建一个 Univer Sheets 应用：

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'

const { univer, univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      UniverPresetSheetsCoreZhCN,
    ),
  },
  presets: [
    UniverSheetsCorePreset({
      container: 'app',
    }),
  ],
})

univerAPI.createWorkbook({})
```

这里返回的 `univerAPI` 对象被称为 Univer 的面板 API（Facade API），通过它可以调用 Univer 提供的许多功能。

<PlaygroundFrame lang="zh-CN" slug="sheets/slim-via-preset" clickToShow />

<Callout type="warning">
  你也可以通过 `@univerjs/presets/preset-sheets-core` 来引入 `UniverSheetsCorePreset`，但必须确保你的构建工具支持 `package.json` 的 `exports` 字段。
</Callout>

#### `createUniver` 方法

`createUniver` 方法接受一个配置对象，其中包含了 Univer 的配置信息，例如语言、主题、插件等。这个方法会返回一个包含了 Univer 实例和 Univer Facade API 实例的对象。

配置对象的部分属性如下：

- `locale`：语言环境，可以是 `LocaleType` 枚举值。
- `locales`：语言包，一个对象，键为语言环境，值为语言包对象。
- `theme`：主题，一个可选主题对象。
- `presets`：一个 preset 数组，包含了需要注册的预设包，例如 `UniverSheetsCorePreset`。
- `plugins`：一个插件数组，包含了需要额外注册的插件。

当你使用了一个未包含在任何预设包中的插件或者你自己实现了一个插件时，可以通过 `plugins` 属性来注册这些插件。也可以选择在获得 Univer 实例后通过 `univer.registerPlugin` 方法来注册插件。

<Callout>
  你可以在 [API Reference / createUniver](/reference/methods/create-univer) 找到更多关于 `createUniver` 方法的详细信息。
</Callout>

### 通过 CDN 使用 Univer

如果你不想使用包管理器，或者只是想快速尝试 Univer 的功能，你可以通过 CDN 引入 Univer 的相关资源。详情请参考 [通过 CDN 使用 Univer](/guides/sheets/getting-started/installation/cdn#preset-mode)。

## 通过插件模式创建

Univer 以插件的形式提供了一系列功能，除了一些产品所必需的核心插件外，你还可以根据需要选择性地引入其它插件。这里仅以最基础的 Univer Sheets 应用为例，介绍如何手动组合安装插件。

与预设模式不同，插件模式默认并不包含 Facade API，以下代码示例中有关 Facade API 的部分都是可选的，你可以根据自己的需求来决定是否删除。

### 使用包管理器

#### 安装

Univer 使用了 React 开发视图（当然这并不影响你在 Vue 或者 Angular 中使用 Univer），使用 Rxjs 来处理数据流，由于这两个库被广泛使用在现代前端开发中，因此我们将它们作为 peerDependencies。而不同的包管理工具在对于 peerDependencies 有着不同的行为策略，因此你可能需要注意一些细节。

<Callout>
  - 如果你正在使用 npm，请确保使用的版本为 npm@7 及以上。这是因为 npm@3 ~ npm@6 并不会正确地安装 `peerDependencies`[^1]。
  - 如果你正在使用 pnpm，请确保使用的版本为 pnpm@8 及以上。如果你正在使用 pnpm@6 ~ pnpm@7，可以尝试配置 `auto-install-peers=true` [^2]来解决依赖安装问题。
  - 如果你正在使用 yarn，你需要手动安装缺失的 `peerDependencies`[^3]，不过别担心，下面的安装命令中已经包含了这些依赖。
</Callout>

<Tabs items={['npm', 'pnpm', 'yarn']}>
  <Tab>
    ```shell
    npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/sheets @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui @univerjs/sheets-ui @univerjs/ui
    ```
  </Tab>
  <Tab>
    ```shell
    pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/sheets @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui @univerjs/sheets-ui @univerjs/ui
    ```
  </Tab>
  <Tab>
    ```shell
    yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/sheets @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui @univerjs/sheets-ui @univerjs/ui react react-dom rxjs
    ```
  </Tab>
</Tabs>

#### 使用

<Callout type="warning" title="注意事项">
  - 并非所有的插件都包含了 facade 包、语言包和样式文件，我们会在每个功能的文档对此进行说明。
  - 样式文件的引入顺序很重要，确保你在依次引入 `@univerjs/design`、`@univerjs/ui` 的 CSS 样式后再引入其他插件的样式文件。
</Callout>

<Steps>
  <Step>
    你需要在项目中引入 Univer 的样式文件、语言包，以及一些必要的插件：

    ```typescript
    import { LocaleType, mergeLocales, Univer, UniverInstanceType } from '@univerjs/core'
    import { FUniver } from '@univerjs/core/facade'
    import DesignZhCN from '@univerjs/design/locale/zh-CN'
    import { UniverDocsPlugin } from '@univerjs/docs'
    import { UniverDocsUIPlugin } from '@univerjs/docs-ui'
    import DocsUIZhCN from '@univerjs/docs-ui/locale/zh-CN'
    import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'
    import { UniverRenderEnginePlugin } from '@univerjs/engine-render'
    import { UniverSheetsPlugin } from '@univerjs/sheets'
    import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'
    import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui'
    import SheetsFormulaUIZhCN from '@univerjs/sheets-formula-ui/locale/zh-CN'
    import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'
    import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui'
    import SheetsNumfmtUIZhCN from '@univerjs/sheets-numfmt-ui/locale/zh-CN'
    import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'
    import SheetsUIZhCN from '@univerjs/sheets-ui/locale/zh-CN'
    import SheetsZhCN from '@univerjs/sheets/locale/zh-CN'
    import { UniverUIPlugin } from '@univerjs/ui'
    import UIZhCN from '@univerjs/ui/locale/zh-CN'

    import '@univerjs/design/lib/index.css'
    import '@univerjs/ui/lib/index.css'
    import '@univerjs/docs-ui/lib/index.css'
    import '@univerjs/sheets-ui/lib/index.css'
    import '@univerjs/sheets-formula-ui/lib/index.css'
    import '@univerjs/sheets-numfmt-ui/lib/index.css'
    ```
  </Step>
  <Step>
    如果你需要使用 Facade API，你可以在这里引入相关的 facade 包，这是可选的（我相信你会需要它们 😀）：

    ```typescript
    import '@univerjs/engine-formula/facade'
    import '@univerjs/ui/facade'
    import '@univerjs/docs-ui/facade'
    import '@univerjs/sheets/facade'
    import '@univerjs/sheets-ui/facade'
    import '@univerjs/sheets-formula/facade'
    import '@univerjs/sheets-numfmt/facade'
    ```
  </Step>
  <Step>
    然后创建一个 Univer 实例，并注册这些插件：

    ```typescript
    const univer = new Univer({
      locale: LocaleType.ZH_CN,
      locales: {
        [LocaleType.ZH_CN]: mergeLocales(
          DesignZhCN,
          UIZhCN,
          DocsUIZhCN,
          SheetsZhCN,
          SheetsUIZhCN,
          SheetsFormulaUIZhCN,
          SheetsNumfmtUIZhCN,
        ),
      },
    })

    univer.registerPlugin(UniverRenderEnginePlugin)
    univer.registerPlugin(UniverFormulaEnginePlugin)

    univer.registerPlugin(UniverUIPlugin, {
      container: 'app',
    })

    univer.registerPlugin(UniverDocsPlugin)
    univer.registerPlugin(UniverDocsUIPlugin)

    univer.registerPlugin(UniverSheetsPlugin)
    univer.registerPlugin(UniverSheetsUIPlugin)
    univer.registerPlugin(UniverSheetsFormulaPlugin)
    univer.registerPlugin(UniverSheetsFormulaUIPlugin)
    univer.registerPlugin(UniverSheetsNumfmtPlugin)
    univer.registerPlugin(UniverSheetsNumfmtUIPlugin)

    univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})

    const univerAPI = FUniver.newAPI(univer)
    ```
  </Step>
</Steps>

<PlaygroundFrame lang="zh-CN" slug="sheets/slim-via-plugin" clickToShow />

#### `univer.registerPlugin` 方法 [#registerPlugin]

`univer.registerPlugin` 方法用于注册一个插件到 Univer 实例中。你可以在创建 Univer 实例后调用这个方法来注册插件。

你可以通过 `univer.registerPlugin(Plugin, options)` 的方式来注册插件，其中 `Plugin` 是要注册的插件，`options` 是可选的配置项，每个插件可能有不同的配置项。

当然你可以可以通过传入一个数组来一次性注册多个插件。这对于需要集中管理插件的场景非常有用。

```typescript
univer.registerPlugin([
  UniverRenderEnginePlugin,
  UniverFormulaEnginePlugin,
  [UniverUIPlugin, {
    container: 'app',
  }],
  UniverDocsPlugin,
  UniverDocsUIPlugin,
  UniverSheetsPlugin,
  UniverSheetsUIPlugin,
  UniverSheetsFormulaPlugin,
  UniverSheetsFormulaUIPlugin,
  UniverSheetsNumfmtPlugin,
  UniverSheetsNumfmtUIPlugin,
])
```

#### 懒加载部分插件

使用插件模式的一个优势是你可以更加灵活地控制插件的加载时机，一种常见的方式是在应用初始化时仅加载必须的插件，而将部分插件的加载时机延迟到首次渲染完成之后。

```typescript
// ...

univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})

import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => {
  univer.registerPlugin(UniverWatermarkPlugin, {
    textWatermarkSettings: {
      content: 'Hello, Univer!',
      fontSize: 36,
    },
  })
})
```

Univer 的 [官方 demo](https://github.com/dream-num/univer/blob/dev/examples/src/sheets/main.ts) 就使用了这样的优化技巧，可供参考。

### 通过 CDN 使用 Univer

如果你不想使用包管理器，或者只是想快速尝试 Univer 的功能，你可以通过 CDN 引入 Univer 的相关资源。详情请参考 [通过 CDN 使用 Univer](/guides/sheets/getting-started/installation/cdn#plugin-mode)。

## 其他发布版本

除了稳定版本之外，Univer 还提供了 alpha / beta 通道。这些版本可以让你提前体验到尚未正式发布的最新功能。但请记住，更多的功能同时意味着更多的风险。这些版本可能包含错误、不完整的功能或者不稳定的特性。请尽可能避免在生产环境中使用这些版本。

### Alpha / Beta 版本

当 Univer 开发团队完成了一个新功能或重大更改时，可能会将其预发布到 alpha 或 beta 通道，你可以通过以下命令安装 alpha / beta 版本的 Univer 包：

```package-install
npm install @univerjs/<package-name>@alpha # Alpha 版本
npm install @univerjs/<package-name>@beta # Beta 版本
```

如果你在使用 alpha / beta 版本时遇到任何问题或者有任何反馈，请通过适当的渠道向 Univer 开发团队报告，比如 [Github Issues](https://github.com/dream-num/univer/issues) 或者 [Discord 社区](https://discord.gg/XPGnMBmpd6)。

祝你在抢先体验中玩得愉快！

## 下一步

* 在 [基础概念](/guides/sheets/getting-started/quickstart#basic-concepts) 章节了解本章中出现的插件、命令和 Facade API 等概念。
* 在 [功能](/guides/sheets/features/core) 相关章节中了解修改电子表格数据的所有操作。

---

[^1]: https://blog.npmjs.org/post/110924823920/npm-weekly-5
[^2]: https://pnpm.io/npmrc#auto-install-peers
[^3]: https://github.com/yarnpkg/yarn/issues/1503
